<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
            "http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<HEAD>



<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<META name="GENERATOR" content="hevea 1.08">
<LINK rel="stylesheet" type="text/css" href="umsroot.css">
<TITLE>
Global References
</TITLE>
</HEAD>
<BODY >
<A HREF="umsroot055.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="umsroot049.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<HR>

<H2 CLASS="section"><A NAME="htoc133">9.7</A>&nbsp;&nbsp;Global References</H2>
<A NAME="globrefs"></A>
Terms stored in non-logical variables and arrays are copies of the
<A HREF="../bips/kernel/storage/setval-2.html"><B>setval/2</B></A><A NAME="@default495"></A> arguments,
and the terms obtained by <A HREF="../bips/kernel/storage/getval-2.html"><B>getval/2</B></A><A NAME="@default496"></A> are thus not identical
to the original terms, in particular their variables are different.
Sometimes it is necessary to be able
to access the original term with its variables, i.e. to have
<I>global variables</I> in the meaning of conventional programming
languages.
A typical example is global state that a set of predicates wants to
share without having to pass an argument pair through all the
predicate invocations.<BR>
<BR>
ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> offers the possibility to store references to general terms
and to access them even inside predicates that have no common variables
with the predicate that has stored them.
They are stored in so-called <B>references</B>.
<A NAME="@default497"></A>
<A NAME="@default498"></A>
For example,
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
:- local reference(p).
</PRE></BLOCKQUOTE>
or
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
:- local reference(p, 0).
</PRE></BLOCKQUOTE>
creates a named reference <B>p</B> (with an initial value of <B>0</B>)
which can be used to store references to terms.
This reference is accessed and modified in the same way as non-logical variables,
with <A HREF="../bips/kernel/storage/setval-2.html"><B>setval/2</B></A><A NAME="@default499"></A>
and <A HREF="../bips/kernel/storage/getval-2.html"><B>getval/2</B></A><A NAME="@default500"></A>,
but the following points are different for references:
<UL CLASS="itemize"><LI CLASS="li-itemize">
the accessed term is identical to the stored term (with its current
substitutions):
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
[eclipse 1]: local reference(a), variable(b).

yes.
[eclipse 2]: Term = p(X), setval(a, Term), getval(a, Y), Y == Term.
X = X
Y = p(X)
Term = p(X)
yes.
[eclipse 3]: Term = p(X), setval(b, Term), getval(b, Y), Y == Term.

no (more) solution.
</PRE></BLOCKQUOTE><BR>
<BR>
<LI CLASS="li-itemize">the modifications are backtrackable, when the execution fails
over the <A HREF="../bips/kernel/storage/setval-2.html"><B>setval/2</B></A><A NAME="@default501"></A> call, the previous value of the global reference is restored
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
[eclipse 4]: setval(a, 1), (setval(a, 2), getval(a, X); getval(a, Y)).
X = 2
Y = Y     More? (;) 

X = X
Y = 1
</PRE></BLOCKQUOTE><BR>
<BR>
<LI CLASS="li-itemize">there are no arrays of references, but the same effect can be
achieved by storing a structure in a reference and using the structure's
arguments. The arguments can then be accessed and modified using
<A HREF="../bips/kernel/termmanip/arg-3.html"><B>arg/3</B></A><A NAME="@default502"></A> and
<A HREF="../bips/kernel/termmanip/setarg-3.html"><B>setarg/3</B></A><A NAME="@default503"></A> respectively.
</UL>
The use of references should be considered carefully.
Their overuse can lead to programs which are
difficult to understand and difficult to optimize.
Typical applications use at most a single reference per module,
for example to hold state that would otherwise have to be passed
via additional arguments through many predicate invocations.<BR>
<BR>
<HR>
<A HREF="umsroot055.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="umsroot049.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
</BODY>
</HTML>
